home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / linklist / source.lha / doc / Intro.3 next >
Text File  |  1993-08-08  |  8KB  |  292 lines
  1. '.so tmac.clman
  2. .TH "Intro"
  3. .IX Intro
  4. .SH NAME
  5. Intro - Introduction to the Generic Linked List.
  6. .SH DESCRIPTION
  7. The Generic Linked List package is a package to define, create, update,
  8. query and delete one or more (nodes of) linked lists, to sort linked
  9. lists, and so on. The user doesn't have to take care of allocating a
  10. number of bytes for a node, inserting on the right place, deleting and
  11. freeing a node and so on.
  12. .br
  13. Different kind of linked lists can be defined. In a \fIsingly\fP linked
  14. list each node points to the next node, in a \fIdoubly\fP linked list
  15. each node points also to the previous node. A \fIchain\fP is a list in
  16. which the last node has a NULL-pointer and in a \fIcircular\fP linked
  17. list the last node points back to the first node.
  18. .br
  19. The package consists of the following routines :
  20. .nf
  21. .if t .ta 0.2i 1.3i
  22.     lDef    define linked list
  23.     lInfo    get information about linked list
  24.     lSort    sort linked list
  25.     lDel    delete linked list
  26.     lDelAll    delete all linked lists
  27.     lDump    dump a linked list to a file
  28.     lUndump    undump a linked list from a file
  29.     lInsNode    insert node
  30.     lInfoNode    get information about node
  31.     lGetNode    get node
  32.     lFndNode    find node
  33.     lFndFlagNode    find node by flag
  34.     lUpdNode    update current node
  35.     lDelNode    delete node
  36.     lInfoIndxNode    get information about node by index
  37.     lGetIndxNode    get node by index
  38.     lUpdIndxNode    update node by index
  39.     lDelIndxNode    delete node by index
  40. .fi
  41. .SH ERROR CODES
  42. .if t .ta 0.2i 1.8i
  43. Here follows an enumeration of the possible error codes, and their
  44. meanings. For each function-call is specified which error codes
  45. could be expected. The marked errors (*) will also be written to
  46. the error-file \fI=listError=\fP.
  47. .nf
  48.     lEMPTY_LIST    linked list doesn't contain any nodes
  49.     lEOL    end of list reached
  50.     lNO_LIST    there are no linked lists defined (*)
  51.     lNOT_DOUBLY    backward searching / retrieving not possible for
  52.         singly linked list (*)
  53.     lNOT_FOUND    node not found
  54.     lOPEN_ERROR    can't open linked list dump file for writing or
  55.         reading (*)
  56.     lSIZE_NE    size of expected data and size of node are not
  57.         equal (*)
  58.     lUNKNOWN_FUNC    function name is unknown (*)
  59.     lUNKNOWN_ID    list identifier is unknown (*)
  60.     lWRONG_CC    parameter \fIcc\fP has wrong value (*)
  61.     lWRONG_INDEX    index out of range (*)
  62.     lWRONG_ORDER    parameter \fIorder\fP has wrong value (*)
  63.     lWRONG_SD    parameter \fIsd\fP has wrong value (*)
  64.     lWRONG_THEORY    parameter \fItheory\fP has wrong value (*)
  65.     lWRONG_WHERE    parameter \fIwhere\fP has wrong value (*)
  66.     lWRONG_WHICH    parameter \fIwhich\fP has wrong value (*)
  67. .fi
  68. .SH LIBRARY
  69. $(TOOLS_HOME)/Lib/list.a
  70. .SH INCLUDE FILE
  71. $(TOOLS_HOME)/List/list.h
  72. .SH PORTABILITY
  73. The Generic Linked List package is a very portable tool. The tool is
  74. developed on UNIX and ported to MSDOS, VAX-VMS and Macintosh. On
  75. those 'ported' machines the library isn't created, but list.c and list.h
  76. were treated the same as all the other source-files (*.[ch]) of the
  77. program, which used the Generic Linked List package.
  78. .SH EXAMPLE
  79. .if t .ta 0.3i 0.6i 0.9i 1.2i 2.2i 3.2i 4.2i 4.5i 4.8i
  80. .nf
  81. #include        <stdio.h>
  82. #include        "list.h"
  83.  
  84. typedef struct rapport {
  85.     char        title[30];
  86.     char        author[15];
  87.     int        date;
  88. } Rapport;
  89. int    rapSz = sizeof(Rapport);
  90.  
  91. static void    insRap(), prRapAll(), prRap();
  92. static int        search(), compare();
  93.  
  94. main()
  95. {
  96.     int            id, code, search_date;
  97.     Rapport        rap;
  98.  
  99.     id = lDef(lSINGLY, lCHAIN);
  100.  
  101.     insRap(id, lFIRST, 1, "Book 1", "People", 890129);
  102.     insRap(id, lFIRST, 2, "Book 2", "More People", 890130);
  103.     insRap(id, lLAST, 1, "Book 3", "Lots of People", 890131);
  104.  
  105.     fprintf(stdout, "lGetNode\n");
  106.     prRapAll(id);
  107.  
  108.     fprintf(stdout, "lGetIndxNode\n");
  109.     code = lGetIndxNode(id, 4, &rap, rapSz);
  110.     prRap(code, &rap);
  111.     code = lGetIndxNode(id, 2, &rap, rapSz);
  112.     prRap(code, &rap);
  113.     code = lGetIndxNode(id, -1, &rap, rapSz);
  114.     prRap(code, &rap);
  115.     code = lGetIndxNode(id, 3, &rap, rapSz);
  116.     prRap(code, &rap);
  117.  
  118.     fprintf(stdout, "lFndNode\n");
  119.     search_date = 890129;
  120.     code = lFndNode(id, lFIRST, search, &search_date, &rap, rapSz);
  121.     prRap(code, &rap);
  122.     code = lFndNode(id, lNEXT, search, &search_date, &rap, rapSz);
  123.     prRap(code, &rap);
  124.     code = lFndNode(id, lNEXT, search, &search_date, &rap, rapSz);
  125.     prRap(code, &rap);
  126.  
  127.     code = lDump(id, "dump");
  128.     fprintf(stdout, "lDump : %d\n", code);
  129.  
  130.     lDel(id);
  131.  
  132.     id = lUndump("dump");
  133.     fprintf(stdout, "lUndump : %d\n", id);
  134.  
  135.     insRap(id, lFIRST, 4, "Book 4", "The Author", 891127);
  136.  
  137.     prRapAll(id);
  138.  
  139.     fprintf(stdout, "lFndFlagNode\n");
  140.     code = lFndFlagNode(id, lFIRST, 1, &rap, rapSz);
  141.     prRap(code, &rap);
  142.     code = lFndFlagNode(id, lNEXT, 1, &rap, rapSz);
  143.     prRap(code, &rap);
  144.     code = lFndFlagNode(id, lFIRST, 2, &rap, rapSz);
  145.     prRap(code, &rap);
  146.     code = lFndFlagNode(id, lFIRST, 7, &rap, rapSz);
  147.     prRap(code, &rap);
  148.     
  149.     fprintf(stdout, "Untouched list\n");
  150.     prRapAll(id);
  151.  
  152.     fprintf(stdout, "lSort\n");
  153.     lSort(id, lDESCENDING, lBUBBLE, compare);
  154.     prRapAll(id);
  155.  
  156.     fprintf(stdout, "lSort\n");
  157.     lSort(id, lASCENDING, lHEAP, compare);
  158.     prRapAll(id);
  159.  
  160.     lDelAll();
  161. }
  162.  
  163. static void
  164. insRap(id, where, flag, title, author, date)
  165. int    id, where, flag, date;
  166. char    *title, *author;
  167. {
  168.     int        code;
  169.     Rapport    rap;
  170.  
  171.     strcpy(rap.title, title);
  172.     strcpy(rap.author, author);
  173.     rap.date = date;
  174.     code = lInsNode(id, where, &rap, rapSz, flag);
  175. }
  176.  
  177. static void
  178. prRapAll(id)
  179. int    id;
  180. {
  181.     int        code;
  182.     Rapport    rap;
  183.  
  184.     code = lGetNode(id, lFIRST, &rap, rapSz);
  185.     prRap(code, &rap);
  186.     while (code == lFIRST || code == lSUCCESS || code == lLAST) {
  187.         code = lGetNode(id, lNEXT, &rap, rapSz);
  188.         prRap(code, &rap);
  189.     }
  190. }
  191.  
  192. static void
  193. prRap(code, rpprt)
  194. int            code;
  195. Rapport        *rpprt;
  196. {
  197.     if (code >= 0)
  198.         fprintf(stdout, "Rapport : '%s' '%s' '%d'\n", rpprt->title,
  199.             rpprt->author, rpprt->date);
  200.     else
  201.         fprintf(stdout, "Return code = %d\n", code);
  202. }
  203.  
  204. static int
  205. search(date, rpprt)
  206. int            *date;
  207. Rapport        *rpprt;
  208. {
  209.     if (rpprt->date > *date)
  210.         return(lFOUND);
  211.     else
  212.         return(lNOT_FOUND);
  213. }
  214.  
  215. static int 
  216. compare(data1, data2)
  217. Rapport *data1, *data2;
  218. {
  219.     int    k = strcmp(data1->author, data2->author);
  220.  
  221.     if (k == 0)
  222.         return(lSAME);    /* key1 == key2 */
  223.     else if (k > 0)
  224.         return(l2LT1);    /* key1 > key2 */
  225.     else if (k < 0)
  226.         return(l1LT2);    /* key1 < key2 */
  227. }
  228. .fi
  229. .sp 2
  230. This example program produces the following output :
  231. .nf
  232.     lGetNode
  233.     Rapport : 'Book 2' 'More People' '890130'
  234.     Rapport : 'Book 1' 'People' '890129'
  235.     Rapport : 'Book 3' 'Lots of People' '890131'
  236.     Return code = -9
  237.     lGetIndxNode
  238.     Return code = -13
  239.     Rapport : 'Book 1' 'People' '890129'
  240.     Return code = -13
  241.     Rapport : 'Book 3' 'Lots of People' '890131'
  242.     lFndNode
  243.     Rapport : 'Book 2' 'More People' '890130'
  244.     Rapport : 'Book 3' 'Lots of People' '890131'
  245.     Return code = -10
  246.     lDump : 0
  247.     lUndump : 1
  248.     Rapport : 'Book 4' 'The Author' '891127'
  249.     Rapport : 'Book 2' 'More People' '890130'
  250.     Rapport : 'Book 1' 'People' '890129'
  251.     Rapport : 'Book 3' 'Lots of People' '890131'
  252.     Return code = -9
  253.     lFndFlagNode
  254.     Rapport : 'Book 1' 'People' '890129'
  255.     Rapport : 'Book 3' 'Lots of People' '890131'
  256.     Rapport : 'Book 2' 'More People' '890130'
  257.     Return code = -10
  258.     Untouched list
  259.     Rapport : 'Book 4' 'The Author' '891127'
  260.     Rapport : 'Book 2' 'More People' '890130'
  261.     Rapport : 'Book 1' 'People' '890129'
  262.     Rapport : 'Book 3' 'Lots of People' '890131'
  263.     Return code = -9
  264.     lSort
  265.     Rapport : 'Book 4' 'The Author' '891127'
  266.     Rapport : 'Book 1' 'People' '890129'
  267.     Rapport : 'Book 2' 'More People' '890130'
  268.     Rapport : 'Book 3' 'Lots of People' '890131'
  269.     Return code = -9
  270.     lSort
  271.     Rapport : 'Book 3' 'Lots of People' '890131'
  272.     Rapport : 'Book 2' 'More People' '890130'
  273.     Rapport : 'Book 1' 'People' '890129'
  274.     Rapport : 'Book 4' 'The Author' '891127'
  275.     Return code = -9
  276. .fi
  277. .SH VERSION
  278. Generic Linked List 0.8, March 1993.
  279. .SH PUBLIC DOMAIN
  280. The Generic Linked List package is in the public domain. If you have
  281. any comments, suggestions, or find any bugs, or make any changes you'd
  282. like to share, please let et e┬ow.
  283. .SH AUTHOR
  284. Copyright (c) 1993 by Anita Eijs (anita@bouw.tno.nl).
  285. .sp 1
  286. .nf
  287. TNO - Bouw - BouwInformatica
  288. P.O. Box 49
  289. 2600 AA Delft
  290. The Netherlands
  291. .fi
  292.